MULTICS TECHNICAL BULLETIN MTB-125 

To: MTB Distribution 

From: T. Casey 

Date: October 2, 197U 

Subject: New list command. 

Anew list command is proposed, to replace the present list, 
list_names, and list_totals commands. A draft MPM writeup is 
attached, and the differences between the current commands and 
the proposed new command are summarized below. 

Certain changes have been previously proposed (in MTB-042) and 
approved by the MCRB. Installation of those changes has been 
postponed to avoid two closely spaced changes to the user 
interface. Those changes are noted in the following summary. 

1. list_names and list_totals are eliminated, and replaced by 
the -name and -total control arguments of the list command. 

2. The -brief control argument (approved but not installed) to 
suppress printing of header lines is replaced by -no_header. 

3. The default order of listing of entry types is changed from 
segs, dirs, msfs, links, to segs, msfs, di rs, 1 inks. That 
order may be varied by the user, by typing the entry type 
control arguments in the desired order. 

k. The specification of what is to be printed and whether or 
not to sort is separated. For example, it is possible to 
sort on one of the dates without its being printed, and vice 
versa. The -sort control argument specifies sorting. If it 
is given, the item to sort on may be specified explicitly, 
or it may be allowed to default to one of the items being 
printed. 

5. Sorting can be done on names (approved but not installed) or 
on records used, in addition to date-time modified and 
date-time used. 

6. All items to be printed may be specified explicitly by 
control arguments (-name, -record, -mode, -dtm, and -dtu), 
or various default combinations may be specified by a single 
control argument. It is possible to have both -dtu and -dtm 
printed. 

7. The -reverse control argument does not Imply sorting by 
-dtu, as it did in the old list. It only reverses the order 
in which the list would otherwise have been printed. 
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8. The -short control argument (approved but not Installed) 
eliminates extra white space during printing of link 
pathnames. The pathnames are printed starting immediately 
after the entry names instead of being aligned in column 35. 

9. The -primary control argument (approved but not installed) 
specifies that additional names should not be printed (just 
the primary name). 

10. The -count control argument specifies that, for 
multiply-named entries, the number of names should be 
printed. 

11. The control arguments -segment, -file, -link, -total, -name, 
and -record will be accepted In both the singular and plural 
form, although they will be documented only in the singular. 
This is a convenience to current users, who may be confused 
by the facts that: 

1) in the old list command, -segment, -link, but -files 
were the accepted spellings, and the command names were 
list_names and l?st_totals; 

2) there presently exist control arguments -name and 
-total; 

3) although most standard control arguments are singular, 
there are the following exceptions: -arguments, -files, 
-ri ng_brackets, and -symbols. 

12. The new messages printed for empty directory, starname not 
found, and no entries of specified type, will be as 
described in MTB-042. 

13. The two problems mentioned in MTB-0l*2 (regarding use of 
starnames), solutions of which were postponed, will now be 
f i xed: 

1) An entry will no longer be listed more than once when 
more than one of the given starnames matches a name on 
the entry. 

2) All names on an entry will be printed (unless -primary 
is given). (The current list command just prints those 
that match one of the given starnames.) 

These problems are caused by deficiencies in 
hcs_$star_l i st_. They will be solved, initially, by using 
the starname "**" in the call to that procedure, and doing 

the star matching in an internal procedure. An external 

user-ring star matching procedure is under consideration, 

but the Interface needs more design work, and will be the 
subject of a future MTB. 
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NAME: list, Is 

The list command prints information about entries in one or more 
directories. Arguments allow the user to specify the directories 
to be listed, the entry types and entry names for which 
information is to be printed, the amount of information to be 
printed for each entry, and the order in which the Information is 
to be printed. 

The default, when no arguments are given, is to list files 
(segments and multi-segment files) of all names, in the working 
directory. For each entry, the mode, records used, primary name, 
and any additional names, will be printed. The two entry types 
will be listed in the order: segments, multi-segment files; 
within each entry type, entries will be printed in the reverse of 
the order in which they were created (most recently created 
first). Preceding the listing of each entry type will be a line 
giving the total number of entries of that type and the total 
records used. 

USAGE: list -entry_names- -control_arguments- 

1) entry_names are the (optional) names of entries to be 

listed. If entry names are given, only 
entries having at least one name matching one 
of the entry names wi 1 1 be 1 I sted, The star 
convention may be used in the entry names. 
Except for the -pathname control argument, 
the positions of the entry names (before, 
after, or among the control arguments) have 
no significance. 

2) control_arguments may be chosen from the following: 

-pathname dir_path 

-pn dir_path causes the directory dir_path to be searched 

for any entry names that follow dir_path on 
the command line. If no entry names follow, 
then the default of ** (all entry names) will 
be used to list the directory dir_path. This 
argument may be given more than once. Any 
entry names preceeding its first occurrence 
refer to the working directory. (However, ** 
is not used by default to list the working 
directory when this argument is given.) 

The following control arguments are used to specify the entry 
types to be 1 isted: 

-segment, -sm print information about segments. 

-mul tisegment_f i le, 

-msf print information about multi-segment files. 
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-file, -f 



print information about files (I.e., segments 
and multi-segment files, in that order). This 
is the default. 
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-branch, -br 

-link, -Ik 
-all, -a 



print information about* branches (i.e., 
segments, mul ti -segment files, and 
directories, in that order). 

print information about links. 

print Information about all entry types 
(segments, multi-segment files, directories, 
and links, in that order). 



When several entry type arguments are given, the entry types will 
be listed in the order in which their corresponding control 
arguments are given. 

The following control arguments are used to specify the amount of 
information to be printed: 



-total, -tt 



print only the heading lines giving total 
entries and total records used, for each 
entry type specified. 



-no_header, -nh omit the heading lines, 
-name, -nm 



-record, -rec 

-mode 

-date_time_used, 
-dtu 



print the heading lines, followed by the 
primary name and any additional names, for 
all selected entries. 

print records used, plus all Information 
printed when -name is given. 

print mode, plus all information printed when 
-record is given. This is the default. 



print date and time last used, plus all 
information printed when -mode is given. 



-da te_t i me_mod I f i ed, 

-dtm print date and time last modified, plus all 

Information printed when -mode is given. 

If both -dtm and -dtu are given, both will be printed (dtm 
first), plus all information printed when -mode is given. 

-primary, -pri do not print the additional names on 

multiply-named entries. 
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-count, -ct for multiply-named entries, print the total 

number of names, after the primary name, on 
the same 1 i ne. 

-brief, -bf This argument is used to decrease the amount 

of infomation printed. Its exact effect 
depends on which other arguments are given. 
If -total is given, then -brief will cause 
the totals information for all selected entry 
types to be abbreviated and printed on a 
single line. Otherwise, it will suppress the 
printing of records or mode when those items 
are implied but not specifically named In 
control arguments. For example, list -dtu 
-brief will cause names and date_t ime_used, 
but not mode and records, to be printed. 

-short, -sh print link pathnames starting immediately 

after the entry names, instead of aligning 
them in column 35. 

The items mode, records, and date_time_used have no meaning for 
links, and there Is an additional item, link_path, associated 
with each link. There is no control argument to specify that 
Hn.K_pa.tb should be printed. It will be printed in all cases 
except the following: 

1) when -total is given; 

2) when -name is given; 

3) when -dtm -brief is given; (a link has a date_tIme_modi f i ed, 
which can be sorted on and printed). 

The following control arguments specify the order in which 
entries will be printed, within each entry type: 

-sort sort entries according to either name, 

records, date_t ime_used, or 

date_time_mod!f led, as spec! fed by the 
control argument immediately following -sort 
(or by the default described below). 

-name, -nm sort entries by primary name. 

-record, -rec sort entries by records used (largest first). 

-date_time_used, 

~ dtu sort entries by date_t ime_used (most recent 

first). 
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-da te_t i me_mod i f i ed, 

-dtm sort entries by date_time_modi f I ed (most 

recent first). 
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-sort/ it specifies the item to be sorted on, and does not cause 
the corresponding item to be printed. If none of these four 
arguments immediately follows -sort, then sorting will be done on 
the first item from the following list which is being printed: 
date_t ime_modi f i ed, date_time_used / records, names. (For 
example, list -dtm -sort is equivalent to list -dtm -sort -dtm.) 
This has the effect of having the list sorted on the item in the 
leftmost column (except for mode, which is never sorted on). 

If -sort is not given, entres will be printed in the reverse of 
the order in which they were created (most recently created 
first). 

-reverse, -rv This argument is used to reverse the order in 

which entries are printed. If -sort is also 
given, the sort will be reversed. Otherwise 
entries will be printed In the order In which 
they were created (oldest fi rst) . 



